home *** CD-ROM | disk | FTP | other *** search
/ SuperHack / SuperHack CD.bin / CODING / C / XTABS200.ZIP / XTABS.DOC < prev   
Encoding:
Text File  |  1995-06-07  |  12.8 KB  |  293 lines
  1. ..[dt] Explains how to use XTabs 2.00 of 26may95 (XTABS.COM)
  2.              XTABS.COM : 2.00 : 26may95
  3.         (c) 1990,1993,1994,1995 by Andrew Stephenson
  4.  
  5. XTABS  began as a simple utility program to filter ASCII files and  optimise
  6. streams  of white space, reducing any mix of spaces, tabs and/or  backspaces
  7. to a minimum form.
  8.  
  9. It  has since been extended in ways that seemed useful and sensible  to  the
  10. author.      Today  it is an "ASCII toolkit", providing  several  occasionally-
  11. lifesaving functions, including handling the small but annoying  differences
  12. which distinguish "WordStar ASCII" from "Real ASCII".
  13.  
  14. The  principal  extensions allow conversion from one "version" of  ASCII  to
  15. another.  The choice now is to/from any mixture of:
  16.  
  17.     PC8    : 8-bit character set used by IBM PCs and their clones
  18.     ASC7    : 7-bit "true" ASCII
  19.     WSN    : WordStar-DOS files (up to version 7.0 so far)
  20.  
  21. In addition, outputs may also be:
  22.  
  23.     C_TEXT  : C / C++ quoted text
  24.     A_TEXT  : ASM quoted text
  25.  
  26. The basic command line is:
  27.  
  28.     xtabs <source_file> <destination_file> [ <optional_commands> ]
  29.  
  30. By  default, XTABS assumes source ('src') and destination ('dst') files  are
  31. PC8: no fancy formatting; 8-bit characters; and characters have fixed width.
  32.  
  33. ASC7  is  very similar to PC8 but assumes characters are 7-bit.      Any  8-bit
  34. characters found in the 'src' cause a single warning message, but an attempt
  35. is made to substitute a suitable 7-bit character for each 8-bit one found.
  36.  
  37. WSN does a quick (but reasonably thorough) conversion from a WordStar 'src',
  38. treating document and non-doc alike.  It assumes the file was "reformed"  by
  39. WordStar itself (which is almost universally so).  Naturally conversion from
  40. elaborate formatting to plain ASCII involves loss of subtlety (while in some
  41. ways  improving on WordStar's own "write marked block to ASCII file").     Dot
  42. commands  other  than ".." are removed.  Character width setter  ".cw n"  is
  43. obeyed.      If 'dst' is also WSN, font-changes are passed on, after  character
  44. width  has  been noted.  By default, widths are assumed to be  1/10"  normal
  45. (^N)  and  1/12"  alternate (^A).  Other hidden  ("symmetrical")  codes  are
  46. interpreted  if useful then discarded; imbedded texts like  annotations  and
  47. footnotes are ignored and discarded.  Single-character formatting codes  are
  48. translated where feasible (binding space, soft hyphen, &c), exceptions being
  49. oddball cases such as ^C and ^F (&c).
  50.  
  51. Hidden formatting codes which are interpreted are:
  52.  
  53.     soft tab
  54.     indent
  55.     centring
  56.     right align
  57.     dot leader
  58.     paragraph numbering
  59.     font change (font width data) -- including Alternate/Normal (^A/^N)
  60.  
  61. NOTE:    The quantity of space chars (&c) needed to fill a gap is  calculated
  62. from gap size and current char width.  This can yield layouts differing from
  63. WordStar's  original screen displays (such as in right-aligned  paragraphs);
  64. nevertheless  these should be correct for the font in use.  But do  not  mix
  65. fonts too freely, or the layout is likely to suffer.
  66.  
  67. C_TEXT  generates C/C++ compatible quoted-text source code.  It  is  assumed
  68. the entire source is to be converted, as seen (less any end-of-file  codes).
  69. One  single quoted text is produced.  Codes outside the range 20..126  which
  70. were  graphics are written within the text in octal backslash notation  (eg,
  71. "\234" == PC8 'pound sterling'); control codes representable by C  notations
  72. \n,  \f, &c are written that way; other control codes are written as  macros
  73. (eg, ASC_ESC for 0x1B or ASCII 'Escape') whose prototype #definitions are in
  74. header file ASC_DEF.H (supplied).  A message warns if macros are used.
  75.  
  76. A_TEXT generates MASM-compatible quoted-text source code.  It is assumed the
  77. entire source is to be converted, as seen (less any end-of-file codes).  One
  78. single  quoted text is produced.  Codes which were graphics are  handled  in
  79. two ways: those whose values lie in the range 20..126 are written within the
  80. text  normally;  others  are written as  numerical  values  (eg,  "value £1"
  81. becomes DB "value ",156,"1").  Control codes all become symbolic  constants,
  82. defined in header file ASC_DEF.ASM (supplied).  A message warns if  symbolic
  83. constants are used.
  84.  
  85. ============================================================================
  86. *** FEATURES:
  87.  
  88. Each command is invoked by the command line argument shown below.  Some take
  89. sub-arguments:  numbers or texts, as appropriate.  Letter case  is  ignored.
  90. If a mistake is detected, XTABS lists valid options.
  91.  
  92.  /O    Overwrite existing 'dst' without permission.
  93.  
  94.     Without  this,  if  'dst'  exists,  the  User  is  asked  to  permit
  95.     overwriting by a simple Y/N response.
  96.  
  97.  /C    Cut control chars (1..31) except Tab, NLine, CRet or FFeed.
  98.  
  99.     Character codes 1..31 (actually, 0..31), usually defined as "control
  100.     codes", are deleted, with the exception of those listed (the minimum
  101.     required for carriage control).  Note that space (32), backspace (8)
  102.     and ASCII tab (9) are always automatically regenerated as  required,
  103.     into a same-sized sequence of tabs and spaces.
  104.  
  105.  /T=n    (n = 1..32, default 8 -- eg: /T=4)
  106.  
  107.     By default, ASCII tab causes a move to the next column whose  number
  108.     is an exact multiple of 8 (counting the first column in each line as
  109.     0).  This command changes the multiplier to any in the range 1..32.
  110.  
  111.     Note that Tab is also known as HT (Horizontal Tab).
  112.  
  113.  /L=n    (n = 0..10000, default 2 -- eg: /L=100)
  114.  /LA
  115.  
  116.     Commands "/L=<number>" and "/LA" allows the User to specify how many
  117.     spaces to leave as spaces.
  118.  
  119.     "/L=<number>" sets a limit: if the number of spaces exceeds it, then
  120.     a mix of tabs and spaces is used; else, spaces are left.
  121.  
  122.     "/LA" leaves all spaces (or tabs &c converted to spaces) as spaces.
  123.  
  124.     White space at the trailing end of a line is always deleted.
  125.  
  126.  /G    `GRddd sequences are to be interpreted as graphic value ddd.
  127.  
  128.     XTABS  tries to distinguish between "graphic" and  "control"  codes.
  129.     Graphic codes cause some kind of mark.  Spaces (a special case)  are
  130.     treated as graphics.
  131.  
  132.     When  converting from WSN to PC8 or ASC7, any graphic code in  range
  133.     1..31  (otherwise  confusable  with an  ordinary  control  code)  is
  134.     written  as  text.  Code value decimal ddd  gives  sequence  `GRddd,
  135.     padded with leading 0s; so code 3 (PC8 "heart" symbol) gives `GR003.
  136.     A warning is issued if this happens.
  137.  
  138.     On  reading 'src' containing such a sequence when command  "/G"  has
  139.     been given, the sequence is (if possible) converted to the  original
  140.     graphic code.
  141.  
  142.     This feature is really only useful when working to/from WSN.
  143.  
  144.  /Q=..  (text = C C++ or ASM -- eg: /Q=C++)
  145.  
  146.     If program source code is being processed, spaces inside quoted text
  147.     must not be changed to tab/space mixes.  Command "/Q=.." causes such
  148.     texts to be treated as if command "/LA" is temporarily active.
  149.  
  150.     Text recognition can be set to C, C++ or MS-style assembly code.  It
  151.     is important to realise that the rules used are by no means as tight
  152.     as those a compiler or assembler would apply, so this option  should
  153.     only  be employed on debugged source code.  Nevertheless, the  rules
  154.     are believed sufficient for most purposes (even detecting comments).
  155.  
  156.  /F=..  Format of 'src' and 'dst'
  157.  /FS=.. Format of 'src' only
  158.  /FD=.. Format of 'dst' only
  159.     (text : PC8 ASC7 or WSN, default PC8 -- eg: /FS=ASC7/FD=WSN)
  160.     ('dst' can also be C_TEXT or A_TEXT)
  161.  
  162.     These commands set the format of 'src' and 'dst'.  Any mix is okay.
  163.  
  164.     For convenience, 'src' and 'dst' can be set together with "/F=..".
  165.  
  166.  /P    Paragraphs are to be identified.
  167.  
  168.     Each paragraph converts to a single text line, by the elimination of
  169.     "newlines"  (except at para end).  Inter-para gaps and  indentations
  170.     at para starts are kept.  Details vary with designated source format
  171.     (see /F= and /FS=, and below).
  172.  
  173.     *** PC8 / ASC7:  New paras are recognised either because they  begin
  174.     with  "white space" (mix of spaces and/or tabs) or because they  are
  175.     preceded by one or more blank lines.  Recognition of a "newline"  is
  176.     complicated  by the possible permutations of <cr> (Carriage  Return,
  177.     ^M),  <lf> (Line Feed, ^J) and <ff> (Form Feed, ^L).  The  following
  178.     are recognised if not mixed too close; some are not really  expected
  179.     to occur and are only catered to for the sake of thoroughness:
  180.          <cr> <lf>
  181.          <cr> <ff>
  182.          <cr>
  183.          <lf> <cr>
  184.          <lf> <ff>
  185.          <lf>
  186.          <ff>
  187.  
  188.     When  a newline is eliminated, all trailing white space on the  line
  189.     just ending is replaced by one space character.
  190.  
  191.     NB: This XTABS version does not convert ASCII paras whose lines  all
  192.     begin with an indentation; each line is treated as a one-line  para.
  193.     A later release may add "paragraph outdenting".
  194.  
  195.     *** WSN: "Soft spaces" and "soft returns" are eliminated, converting
  196.     paras of all types: right-justified, right-aligned and centred.  Any
  197.     para which is indented by "soft" indents (such as by a non-zero left
  198.     margin setting) is also converted.
  199.  
  200.  /CR=.. Replace all Carriage Returns (^M, ASCII 13) by..  (default CR)
  201.  /LF=.. Replace all Line Feeds (^J, ASCII 10) by..      (default LF)
  202.  /FF=.. Replace all Form Feeds (^L, ASCII 12) by..      (default FF)
  203.     (text : SUPP CR LF FF SP CRLF or LFCR -- eg: /LF=SUPP/FF=CR)
  204.  
  205.     These three commands cause relevant codes to be replaced by whatever
  206.     is selected, if found:
  207.  
  208.          SUPP    suppresses the code (ie, deletes it);
  209.          CR         substitutes CR;
  210.          LF         substitutes LF;
  211.          FF         substitutes FF;
  212.          SP         substitutes one ASCII space;
  213.          CRLF    substitutes two-code sequence CR,LF; and
  214.          LFCR    substitutes two-code sequence LF,CR.
  215.  
  216.     Substitution is not recursive.  CR->LF->FF->CR, for instance, is not
  217.     possible in one pass of XTABS.
  218.  
  219.  /W=n    (n=10..32000, default 70 in C_TEXT, 74 in A_TEXT -- eg: /W=100)
  220.  
  221.     This  command only does anything useful when the destination is  set
  222.     to either C_TEXT or A_TEXT; otherwise it is obeyed then ignored.
  223.  
  224.     If an output line reaches the set limit after an element (character,
  225.     macro, symbolic constant, &c) has been generated, a new line starts.
  226.     Lines can go slightly beyond the /W= limit -- how far depends on the
  227.     mode: in C_TEXT an overlap of 9 chars is possible; in A_TEXT, 5.
  228.  
  229.  /EOF    Write an ASCII EOF (^Z) at the end of the output.
  230.  
  231.     By default, output ends when the translation of the source ends,  to
  232.     fit with modern practice.  However, some older software may  require
  233.     text files to have ASCII End-Of-File characters.
  234.  
  235.     Note that this differs from pre-2.00 XTABS, which always output ^Z.
  236.  
  237.  /H    Display help screen.
  238.  
  239.     The Help screen is displayed then XTABS quits back to DOS.  Help  is
  240.     also given if an error is detected.
  241.  
  242. ============================================================================
  243. *** HISTORY:
  244.  
  245. Ver.    Dated        Notes
  246. ----    ------        -----
  247. 0.10    2apr90        XTABS begun. Slowly evolved as needs dictated.
  248. 1.30    2jan94        First general release of XTABS, via BBS.
  249. 1.31    5jan94        Bug fix: WSN dot cmnds not always deleted properly.
  250. 1.32    7jan94        Added /CR=, /LF= and /FF= commands.
  251. 1.33    7jan94        Polish. Added /CR=, /LF=, /FF= options SP and LFCR.
  252. 1.40    26may94        Added /P command.
  253. 1.41    1jun94        Bug fix: /P mode stuck 'on' for ASC7/PC8 src.
  254. 1.42    11nov94        Trivial redesign of Help screen.
  255. 1.50    4feb95        Added destinations C_TEXT & A_TEXT, with /W command.
  256. 1.51    8feb95        Polishing.
  257. 2.00    26may95        Radical internal rebuild. Bug fixes (eg, in WSN mode
  258.             dot commands now recognised inside paragraphs.)  New
  259.             /EOF command (^Z no longer appended automatically).
  260.  
  261. ============================================================================
  262. *** ACKNOWLEDGEMENTS:
  263.  
  264. Thanks  to Softkey International (UK) Ltd, formerly  WordStar  International
  265. (UK) Ltd, for file format information.
  266.  
  267. ============================================================================
  268. *** THE LEGAL STUFF:
  269.  
  270. Copyright  (c) 1990,1993,1994,1995 by Andrew Stephenson who  hereby  asserts
  271. his right to be identified as author of this work, in accordance with the UK
  272. Designs  and  Patents  Act, 1988.  XTABS is "freeware".  It is  not  in  the
  273. public  domain.  You may make copies freely for NON-COMMERCIAL USE  but  the
  274. author continues to hold all rights in it.  This work with all its files may
  275. be  included on a CD-ROM provided that: either, the author is sent  one  (1)
  276. copy,  at no charge to him, on each occasion of publication; or, the  author
  277. first gives explicit permission for such inclusion.
  278.  
  279. This  software product runs on IBM-compatible computers under PC-DOS or  its
  280. equivalent.  Displays are monochrome text oriented.  Users use this  product
  281. entirely at their own risk: XTABS is NOT represented as being bug-free.
  282.  
  283. ============================================================================
  284. Andrew Stephenson
  285.  
  286. at:  "Summerfield", Elsing Road, Lyng, Norwich, Norfolk, NR9 5RR, UK
  287. or:  ames@deltrak.demon.co.uk
  288.  
  289. who  would be glad of a reaction saying whether the software worked and  how
  290. useful it was/is/may be, to assist his enthusiasm and planning.
  291.  
  292. END
  293.